Repository navigation
Highlight CQL and other new languages, and refresh the highlighting theme - #213
Merged
Merged
Conversation
- Register highlightjs-cql 1.0.0 for cql and cqlsh blocks, replacing the SQL stand-in. It colors CQL by role (types, names, setting names, functions, bind markers, cqlsh prompts and commands) for Apache Cassandra, DSE, HCD, and Astra DB. - Register GraphQL (graphql, gql), ported from highlight.js 11.12.0, which highlight.js 9 lacks. Output matches highlight.js 11 on all 19 GraphQL blocks in the docs. - Add a license notice for the bundled highlighting code to the top of highlight.bundle.js. - Style placeholders (<keyspace_name>) in italics instead of the error color. - Keep lint and format off src/js/vendor/languages, which holds grammars maintained elsewhere.
- Give each kind of token its own color: keywords purple, types cyan, functions and headings pink, keys and setting names indigo, strings green, numbers and literals orange, variables and placeholders amber, prompts and comments gray, deleted lines red. - Meet WCAG AA contrast (4.5:1) in both themes. The colors come from new --ds-code-* variables: shade 700 of each palette family in the light theme and shade 400 in the dark theme. Before, strings, numbers, types, literals, and function names were below 4.5:1 in the light theme (as low as 3.41:1), and variables and XML names were below it in the dark theme (3.96:1). - Stop using the error color for variables and markup, and stop coloring whole parameter lists. - Italicize comments. Placeholders stay italic. - Make cqlsh prompts unselectable, like console prompts.
Setting names (such as REPLICATION in WITH REPLICATION = ...) were indigo, next to purple keywords: a color difference (CIEDE2000) of only 8.9 in the light theme, and harder still to tell apart in capital letters. They are now cyan, a difference of 28.9. Types and built-ins move from cyan to lime, which also keeps them far from the keywords they sit beside (TEXT PRIMARY KEY). Both colors still meet WCAG AA contrast in both themes.
The preview's code page had one CQL block and no GraphQL, YAML, or XML, so a reviewer of the UI preview couldn't see most of what this branch changes. Add a "Syntax highlighting samples" section with CQL statements, a CQL syntax summary with placeholders, a cqlsh session, GraphQL, YAML, and XML. Preview pages aren't part of the UI bundle.
IBM Docs, where these docs are moving, reads the language name exactly as written, so a block labeled [source,language-cql] isn't highlighted there. Normalizing the label here would hide that problem from writers. Without the normalization, such blocks are plain on this site too, which shows that the label needs fixing. Protobuf highlighting, added in the same earlier commit, stays.
The vendor scripts were meant to be minified, all except floatingui.js, but a misplaced parenthesis made the build skip all of them. Minify them as intended, with a per-file condition. - Minifying drops the license notices from the highlight.js bundle, which its BSD license requires us to keep. Record each bundle's /*! ... */ notices before minifying and put back any that are lost. - The zooming and Floating UI bundles carried no license notice at all, though their MIT licenses ask for one. Add one to each. - A first visit now downloads 88 KB of these scripts compressed, instead of 113 KB. The highlight.js bundle drops from 56 KB to 35 KB.
This brings in the change from the powershell-highlighting branch. - Register highlight.js's PowerShell grammar, which also answers to ps and ps1. The Astra CLI's Windows instructions and the C# driver's NuGet commands are PowerShell, now labeled shell and cs; relabeled, they'll be highlighted here and on IBM Docs. - Stop registering the INI grammar a second time as toml. The INI grammar already answers to toml. - Add a PowerShell sample to the UI preview, since no page labels a block powershell yet.
Match highlightjs-cql's dist/cql.cjs, which rewords one comment about DataStax Enterprise's PENDING keyword. Highlighting is unchanged.
Setting names share their color with JSON and YAML keys, XML attribute names, and GraphQL argument names. The cyan in use now is only 25 apart from string values (CIEDE2000), and the indigo before it only 8.9 from keywords in light mode. Sky is at least 28.8 from keywords and 33.3 from strings, in both themes. - Contrast on the code background is 5.68:1 in light mode (sky 700) and 6.95:1 in dark mode (sky 400). Every highlighted token in the UI preview still passes WCAG AA in both themes.
Contributor
|
UI bundle preview build successful! ✅ |
|
Build successful! ✅ |
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Jira: DOC-3966
Summary
cqlwas an alias for the SQL grammar. It is now highlightjs-cql, a grammar built for CQL. It covers Apache Cassandra, DataStax Enterprise, HCD, and Astra DB, and it was tested against Cassandra's own parser.gulp.d/tasks/build.jshad skipped all of them. A first visit now downloads 88 KB of these scripts compressed instead of 113 KB, and the highlighting bundle drops from 56 KB to 35 KB. License notices are kept through minification, and the zooming and Floating UI bundles get the MIT notices they lacked.tomlregistration is dropped, since theinigrammar already answers totoml.New theme (light and dark modes)
How to review
UI preview. Open the Code page, then its "Syntax highlighting samples" section. Check it in both light and dark mode. Link: https://d5rxiv0do0q3v.cloudfront.net/docs-ui-drafts/syntax-highlight-fixes/asciidoc/code.html#syntax-highlighting-samples
Draft docs site. After this PR is merged, when we open the PR to update the UI bundle in the
datastax-docs-siterepo, open the full site draft build and compare these pages with production, in both light and dark mode:now()and types likeVECTOR<FLOAT, 5>get their own colors. Column names such asidandcommentare no longer colored as keywords.<list_name>in the syntax summaries are italic.Minified scripts. In the UI preview, open the highlighting script in the browser's developer tools. It's minified, and it starts with the license notices.
Accessibility. In a sample of 246 colored tokens across the 14 most common languages in the docs, 101 failed WCAG AA contrast in light mode before this change, and 10 in dark mode. None do now.
Notes for reviewers
Vendored grammars.
src/js/vendor/languages/holds grammars that are maintained elsewhere. Its README says where each comes from and how to update it. Lint and format skip this folder, because the files keep their upstream formatting.License notice. A comment at the top of
highlight.bundle.jslists the bundled highlighting code and its licenses:The comment is carried into the published bundle. The build now puts back any license notice that minification drops.
Colors. Syntax colors are new
--ds-code-*variables insrc/css/vars/light.cssandsrc/css/vars/dark.css. They use shade 700 of each palette color in the light theme and shade 400 in the dark theme.Prompts. cqlsh prompts (
cqlsh>) can't be selected, the same as console prompts.Not addressed here (pre-existing): the toolchain pins Node 16, and
npm installreports dependency vulnerabilities.